home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus 2000 #4 / Amiga Plus CD - 2000 - No. 4.iso / Tools / Up2Date / WarpUP4_UPD / WarpUP-WarpOS / hwdrivers / WarpHW.txt
Encoding:
Text File  |  1999-04-11  |  10.8 KB  |  325 lines
  1.  
  2.         WarpUp hardware driver protocol version 1
  3.         © 4.2.1998  HAAGE&PARTNER Gmbh
  4.         Written by Sam Jordan
  5.         $VER: WarpHW.txt 1.0 (4.2.98)
  6.         -----------------------------------------
  7.  
  8. 1. Introduction
  9. ---------------
  10.  
  11. This document describes the WarpUp hardware driver protocol which allows
  12. anyone to write driver software for PowerPC hardware supporting the
  13. WarpUp-HAL for dual processor systems.
  14.  
  15. The WarpUp-HAL was splitted up since version 3 into two parts, the main
  16. HAL (warp.library) and the hardware driver (warpHW.library). The warp.library
  17. now opens the warpHW.library and calls its functions to get control over
  18. the specific hardware. Note that the hardware drivers only work with
  19. warp.library version 3 and higher.
  20.  
  21. Every hardware which provides a driver named 'warpHW.library' will work with
  22. the WarpUp-HAL (and therefore with WarpOS). These different libraries can
  23. be distinguished by the tool program 'GetDriverInfo' which prints out the
  24. identification string and the largest protocol number supported. This tool
  25. should always be found with this documentation together. Just run it and
  26. it will print out the information, if the warpHW.library was found.
  27.  
  28. 2. Requirements
  29. ---------------
  30.  
  31. To write a WarpUp hardware driver you need a 68K C compiler, a PPC C compiler
  32. supporting WarpUp and a linker which can deal with the extended hunk format.
  33. StormC supports all this and other compilers might support it in future.
  34. Of course, it's possible to write the driver completely in assembler, but
  35. better use C instead.
  36.  
  37. The WarpHW.library is a mixed shared library, since it provides functions
  38. for the 68K side and the PowerPC side.
  39.  
  40. 3. API notes
  41. ------------
  42.  
  43. This document describes the protocol version 1, which is the first version
  44. released. If anyone needs more API functions because of special hardware
  45. features or for other reasons, this protocol will be enhanced and new
  46. versions will be released. In this case it's very likely that the HAL itself
  47. must be updated to support the new API. But older hardware drivers will work
  48. without modification, since the WarpUp-HAL will ask the driver for the maximal
  49. protocol version which is supported.
  50.  
  51. Anyone which requires enhancements to the protocol should contact us, the
  52. appropriate links can be found at the bottom of this document.
  53.  
  54. 4. Template
  55. -----------
  56.  
  57. In the directory there is a template for a new hardware driver which should
  58. be helpful for development. You will find the following files of importance:
  59.  
  60. - WarpHW.¶         : 68K-Storm-Project, which is the main project here
  61. - WarpHW_PPC.¶     : PPC-Storm-Project, which is a subproject of WarpHW.¶
  62. - WarpHW.c         : C source compiled for 68K, containing the 68K API
  63.                      functions
  64. - WarpHW_PPC.c     : C source compiled for PPC, containing the PPC API
  65.                      functions
  66. - WarpHW_68K.s     : A small 68K assembler function to perform NOP
  67.                      synchronisation
  68. - WarpHW_PPC_asm.p : Some small PPC assembler functions to perform ISYNC/SYNC
  69.                      synchronisation and to provide some important
  70.                      functions for the linker.
  71. - WarpHW_lib.fd    : The FD file for the WarpHW.library
  72.  
  73. First compile the PPC project to gain the object files 'WarpHW_PPC.o' and
  74. 'WarpHW_PPC_asm.o'. Afterwards add those object files to the 68K project
  75. and compile the main project. Finally link everything together to a
  76. shared library.
  77.  
  78. Important Note: Never create a Storm-Project with 'Mixed Binary' option
  79. to write a hardware driver. This can't work because of callbacks to the
  80. powerpc.library/warp.library in the library initialisation of the
  81. warpHW.library. It's the best way to take the template project and to
  82. add the code.
  83.  
  84. 5. Protocol description
  85. -----------------------
  86.  
  87. This chapter discusses the interaction between the WarpUp-HAL and the
  88. hardware drivers.
  89.  
  90. a) Evaluating the address of the PowerPC exception area
  91.  
  92. The WarpUp-HAL needs the location of the PowerPC exception area and
  93. therefore calls the WarpHW API function 'InitBootArea'. This function
  94. must return this location and should set up the hardware so that the
  95. address space of the exception area (starting from 0xfff00000) is
  96. mapped to the real location. This mapping can't be done by the MMU
  97. since the exception area is located at physical address 0xfff00000.
  98. Hardware logic should perform this mapping.
  99.  
  100. The exception area has to be located in writeable address space. The
  101. API function is allowed to allocate the required memory. Note
  102. that the exception area has to be aligned on a 64KB boundary and
  103. must be at least 64KB large.
  104.  
  105. Note that the first 256 bytes of the exception area space are
  106. reserved for the WarpUp HAL itself.
  107.  
  108. b) Resetting the PowerPC
  109.  
  110. After step a) the reset exception routine is prepared and some fields
  111. of the exception area are initialized. After that, the PowerPC is
  112. reset by calling the WarpHW API function 'BootPowerPC'. This function
  113. should initialize all hardware registers and reset the PPC
  114. processor which should start execution at 0xfff00100, where the
  115. reset routine is located.
  116.  
  117. c) Causing the PowerPC interrupt
  118.  
  119. On dual processor systems, the WarpUp-HAL needs the possibility to
  120. cause an external PPC interrupt by the 68K processor. In this case
  121. the WarpHW API function 'CauseInterrupt' is called. This function
  122. should drive the INT signal of the PPC to active state. The signal
  123. should be kept in active state, until the interrupt was confirmed
  124. by the PPC interrupt handler (by calling 'ConfirmInterrupt', see
  125. below).
  126.  
  127. d) Confirming the PowerPC interrupt
  128.  
  129. After an external interrupt was caused from the 68K side, the
  130. PowerPC enters into the external interrupt handler. This handler
  131. calls the WarpHW API function 'ConfirmInterrupt' to confirm the
  132. interrupt. This function should drive the INT signal to inactive
  133. state.
  134.  
  135. 6. API description
  136. ------------------
  137.  
  138. This chapter dicusses the API functions in more detail. For better
  139. readability, they are written in autodoc format.
  140.  
  141. Note, that all API functions should preserve the smalldata base. Use
  142. the keyword __saveds in the function declaration or use the template
  143. sources.
  144.  
  145. Also note, that you can use the functions 'sync' (68K) and
  146. 'syncPPC' (PPC) to perform memory/command synchronisation. 'sync'
  147. executes one NOP instruction, 'syncPPC' an ISYNC/SYNC pair. Both
  148. functions can be found in the template project as assembler sources.
  149. If the appropriate objects are present, just take them and link with
  150. the other objects.
  151.  
  152.  
  153. warpHW.library/GetDriverID                           warpHW.library/GetDriverID
  154.  
  155.     NAME
  156.         GetDriverID - returns a driver identification string (V1)
  157.  
  158.     CPU
  159.         680x0
  160.  
  161.     MANDATORY
  162.         Yes
  163.  
  164.     SYNOPSIS
  165.         IDstring = GetDriverID(void)
  166.         d0
  167.  
  168.         char* GetDriverID(void)
  169.  
  170.     FUNCTION
  171.         This function returns a string identifying this WarpUp hardware
  172.         driver. The string should be of the following format:
  173.  
  174.         "WarpUp hardware driver for <hardware identification>"
  175.  
  176.         The hardware identification must be unique across several
  177.         PPC hardware.
  178.  
  179.     RESULT
  180.         IDstring - The identification string of this WarpUp hardware driver
  181.  
  182. warpHW.library/SupportedProtocol               warpHW.library/SupportedProtocol
  183.  
  184.     NAME
  185.         SupportedProtocol - returns the max. protocol version supported (V1)
  186.  
  187.     CPU
  188.         680x0
  189.  
  190.     MANDATORY
  191.         Yes
  192.  
  193.     SYNOPSIS
  194.         Version = SupportedProtocol(void)
  195.         d0
  196.  
  197.         int SupportedProtocol(void)
  198.  
  199.     FUNCTION
  200.         This function returns a version number telling the WarpUp HAL the
  201.         highest driver protocol version which is supported by this driver.
  202.         This function exists for backward compatibility, so that the WarpUp
  203.         HAL won't call functions which don't exist in older hardware drivers.
  204.  
  205.     RESULT
  206.         Version - The max. driver protocol version number supported
  207.  
  208. warpHW.library/InitBootArea                         warpHW.library/InitBootArea
  209.  
  210.     NAME
  211.         InitBootArea - evaluates the address of the PowerPC exception area (V1)
  212.  
  213.     CPU
  214.         680x0
  215.  
  216.     MANDATORY
  217.         Yes
  218.  
  219.     SYNOPSIS
  220.         ExcArea = InitBootArea(void)
  221.         d0
  222.  
  223.         void *InitBootArea(void)
  224.  
  225.     FUNCTION
  226.         This function returns the address of the PowerPC exception area.
  227.         This area must be in writeable address space and must be aligned
  228.         to a 64KB boundary and must be at least 64KB large.
  229.  
  230.         The function should setup the hardware so that it maps the
  231.         physical address space of the exception area (starting with address
  232.         0xfff00000) to the real location of the exception area.
  233.  
  234.         This function can allocate the memory itself and doesn't have to
  235.         care for memory freeing.
  236.  
  237.     RESULT
  238.         ExcArea - Address of the PowerPC exception area
  239.  
  240. warpHW.library/BootPowerPC                           warpHW.library/BootPowerPC
  241.  
  242.     NAME
  243.         BootPowerPC - resets the PowerPC (V1)
  244.  
  245.     CPU
  246.         680x0
  247.  
  248.     MANDATORY
  249.         Yes
  250.  
  251.     SYNOPSIS
  252.         void BootPowerPC(void)
  253.  
  254.         void BootPowerPC(void)
  255.  
  256.     FUNCTION
  257.         This function resets the PowerPC processor which should start
  258.         execution at physical address 0xfff00100, where the reset
  259.         routine was installed by the WarpUp HAL.
  260.  
  261.         In this function, all hardware registers which require initialization,
  262.         should be initialized.
  263.  
  264. warpHW.library/CauseInterrupt                     warpHW.library/CauseInterrupt
  265.  
  266.     NAME
  267.         CauseInterrupt - trigger the PowerPC' external interrupt (V1)
  268.  
  269.     CPU
  270.         680x0
  271.  
  272.     MANDATORY
  273.         Yes
  274.  
  275.     SYNOPSIS
  276.         void CauseInterrupt(void)
  277.  
  278.         void CauseInterrupt(void)
  279.  
  280.     FUNCTION
  281.         This function causes a PowerPC external interrupt. It should
  282.         drive the INT signal of the PowerPC to active state and should
  283.         keep it active, until the interrupt was confirmed from the PPC
  284.         side (see 'ConfirmInterrupt')
  285.  
  286. warpHW.library/ConfirmInterrupt                     warpHW.library/ConfirmInterrupt
  287.  
  288.     NAME
  289.         ConfirmInterrupt - confirms the external interrupt (V1)
  290.  
  291.     CPU
  292.         PowerPC
  293.  
  294.     MANDATORY
  295.         Yes
  296.  
  297.     SYNOPSIS
  298.         void ConfirmInterrupt(void)
  299.  
  300.         void ConfirmInterrupt(void)
  301.  
  302.     FUNCTION
  303.         This function is called from the WarpUp-HAL in the external
  304.         interrupt exception handler to confirm the interrupt. The
  305.         function should drive the INT signal to inactive state.
  306.  
  307.     NOTES
  308.         This function is called with data cache frozen, therefore
  309.         any accesses which don't hit the cache are noncachable.
  310.         And the hardware registers should never be located in the
  311.         cache, since they are never accessed outside of
  312.         'ConfirmInterrupt' by the PowerPC.
  313.  
  314. 7. Contact addresses
  315. --------------------
  316.  
  317.         regular mail:                   eMail:
  318.  
  319.         HAAGE&PARTNER GmbH              s.jordan@haage-partner.com
  320.         Mainzer Starße 10A
  321.         61191 Rosbach
  322.         Tel: 06007/930050
  323.         Fax: 06007/7543
  324.  
  325.